API Reference

Functions

Function	Signature	Purpose
giftmeMakePayment	(req: GiftmePaymentRequest) → Promise<GiftmePaymentResponse>	Opens the native pay sheet for the order referenced by orderToken.
giftmeGetAuthCode	(req: GiftmeAuthCodeRequest) → Promise<GiftmeAuthResponse>	Returns a one-time code that can be exchanged for an API access token.
isMiniStoreContext	() → boolean	true when the page is loaded inside Giftme's WebView (navigator.userAgent contains Giftme).
giftmeGetCurrentLocation	(timeout?: number) → Promise<GiftmeLocationResponse>	Requests the user's current GPS location.
giftmeGetCameraData	(timeout?: number) → Promise<GiftmeMediaResponse>	Opens the device camera and returns the captured image as base64.
giftmeCheckPermission	(req: GiftmePermissionRequest) → Promise<GiftmePermissionResponse>	Checks if a specific permission is granted.
giftmeRequestPermission	(req: GiftmePermissionRequest) → Promise<GiftmePermissionResponse>	Requests a specific permission from the user.

Request Objects

GiftmePaymentRequest

interface GiftmePaymentRequest {
  /** Server-generated token that represents the order the user is about to pay for */
  orderToken: string;
}

GiftmeAuthCodeRequest

interface GiftmeAuthCodeRequest {
  /** The storefront identifier you received from Giftme */
  miniStoreId: string;
}

GiftmePermissionRequest

interface GiftmePermissionRequest {
  /** The permission to check or request: 'camera', 'location', 'gallery', 'photos', or 'storage' */
  permission: string;
}

Response Objects

GiftmeAuthResponse

The response shape may vary, but you can rely on at least:

type GiftmeAuthResponse =
  | { status: "SUCCESS"; payload: { message: string; token: string } }
  | { status: "CANCELLED"; payload: { message: string } }
  | { status: "ERROR"; payload: { message: string } };

GiftmePaymentResponse

The response shape may vary, but you can rely on at least:

type GiftmePaymentResponse =
    | { status: 'SUCCESS'; payload: { ...data }}
    | { status: 'CANCELLED'; payload: { message: string }} // Cancelled by user
    | { status: 'ERROR'; payload: { message: string, ...data }};

GiftmeLocationResponse

interface GiftmeLocationPayload {
  latitude: number;
  longitude: number;
  accuracy?: number;
}

type GiftmeLocationResponse =
  | { status: "SUCCESS"; payload: GiftmeLocationPayload }
  | { status: "ERROR"; payload: { message: string } };

GiftmeMediaResponse

interface GiftmeMediaPayload {
  fileBase64: string;
  meta: {
    width: number;
    height: number;
    type: string;
  };
}

type GiftmeMediaResponse =
  | { status: "SUCCESS"; payload: GiftmeMediaPayload }
  | { status: "CANCELLED"; payload: { message: string } }
  | { status: "ERROR"; payload: { message: string } };

GiftmePermissionResponse

type GiftmePermissionResponse =
  | { status: "GRANTED"; payload: { [permissionName: string]: number } }
  | {
      status: "DENIED";
      payload:
        | { [permissionName: string]: number; permanentlyDenied?: boolean }
        | { message: string };
    };

Usage Examples

Get Current Location

const locationResult = await giftmeGetCurrentLocation();

if (locationResult.status === "SUCCESS") {
  const { latitude, longitude, accuracy } = locationResult.payload;
  console.log(`Location: ${latitude}, ${longitude} (accuracy: ${accuracy}m)`);
}

Capture Image from Camera

const cameraResult = await giftmeGetCameraData();

if (cameraResult.status === "SUCCESS") {
  const { fileBase64, meta } = cameraResult.payload;

  // Display the image
  const imgElement = document.createElement("img");
  imgElement.src = `data:${meta.type};base64,${fileBase64}`;
  document.body.appendChild(imgElement);

  console.log(`Image size: ${meta.width}x${meta.height}`);
}

Check and Request Permissions

// Check if camera permission is granted
const checkResult = await giftmeCheckPermission({ permission: "camera" });

if (checkResult.status === "GRANTED") {
  console.log("Camera permission already granted");
} else {
  // Request permission if not granted
  const requestResult = await giftmeRequestPermission({ permission: "camera" });

  if (requestResult.status === "GRANTED") {
    console.log("Camera permission granted");
  } else if (requestResult.payload.permanentlyDenied) {
    console.log("Permission permanently denied - user must enable in settings");
  }
}